PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / qlib.exe / DATA.DOC < prev next >

Wrap

Text File | 1992-02-24 | 45.6 KB | 1,232 lines

DATA routines manipulate numeric or string data. Single data points or portions of arrays may be shifted left or right (equivalent to multiplying or dividing by powers of 2), integers may be added to selected array elements, or arrays may be multiplied by real-number constants. INSTR-like functions find the LAST match of a sub-string in a string, count the number of matches of a sub-string in a string, or remove portions of strings. QLIB Array subroutines are more compact than equivalent BASIC FOR ... NEXT loops, and can be as much as 20 times faster. (Registered version only) Many DATA subroutines support huge model arrays. To use huge arrays, start QB with the /ah switch, compile using BC's /ah switch, and link with QLIBH.LIB instead of QLIB.LIB. QLIB DATA routines generally follow these rules: 1) Several subroutines require a math coprocessor (either 8087, 80287 or 80387, referred to as 80x87). This requirement is clearly stated. Several subroutines will use the 80x87 if available or will use QuickBASIC's (or BC7/QBX's) 8087 emulator. 2) a subroutine with INT, LNG, SNG or DBL in its name is to be used with integer, long integer, single-precision real or double-precision real number data, respectively. Subroutines with CUR in the name are for BC7/QBX's CURRENCY data type. 3) subroutines using real numbers (SNG or DBL) require data in IEEE floating-point format unless otherwise stated. This is the default format for Microsoft's current BASIC and QuickBASIC compilers; in most cases this requirement is not a problem. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: AddINTArray(s%, p%, n%, value%, oops%) object code: addintn.obj Subroutine: AddLNGArray(s%, p%, n%, value%, oops%) object code: lngarray.asm Adds an integer to the first n% elements of an integer or long integer array. You can subtract by adding a negative number. If the addition caused any of the array elements to overflow, oops% indicates the number of overflows. Example: DIM Array1%(10000) . . value% = -6: n% = 1000 s% = VARSEG(Array1%(0)) ' s% = segment where array located p% = VARPTR(Array1%(0)) ' p% = offset of array in segment CALL AddINTArray(s%, p%, n%, value%, oops%) IF oops% THEN PRINT "Uh oh, overflowed somewhere..." REM we just subtracted six from the first 1000 elements of the array REM Array1%(). ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: AddDBL(a#, b#, c#, oops%) object code: adddbl.obj AddDBL adds two double-precision floating point numbers, returning c# as the result and an error flag to warn of overflow, rather than crashing the program on overflow. a# and b# may be positive or negative. Oops% = 0 if no problems, or oops% = -1 if an overflow occurred. If AddDBL overflowed, the previous value of c# will not be lost. AddDBL is up to 3 times faster than BASIC on computers without 8087. 8087 not required. Example: a# = 123.456789 b# = -23.456 CALL = AddDBL(a#, b#, c#, oops%) ' results: oops% = 0, c# = 100.00789 IF oops% = -1 THEN ' check for errors anyway . . . ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: AddSNG(a!, b!, c!, oops%) object code: addsng.obj AddSNG adds two single-precision floating point numbers, returning c! as the result and an error flag to warn of overflow, rather than crashing the program on overflow. a! and b! may be positive or negative. Oops% = 0 if no problems, or oops% = -1 if an overflow occurred. If AddSNG overflowed, the previous value of c! will not be lost. AddSNG is up to 9 times faster than BASIC on computers without 8087. Example: a! = 123.456 b! = -23.456 CALL = AddSNG(a!, b!, c!, oops%) ' results in oops% = 0, c! = 100.00 IF oops% = -1 THEN ' check for errors anyway . . . ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: segptr% = AllocMem(bytes%) object file: allocmem.obj (q$alloc.obj) AllocMem allocates memory from DOS memory space for QLIB's use. Unlike BASIC arrays, memory allocated by AllocMem will not move around, so the address of these memory blocks need not be updated before use. Use FreeMem(segptr%) to release the memory block for other use. This memory space may be used with any QLIB subroutine or function which uses VARSEG and VARPTR parameters; segptr% returned by AllocMem would be used in place of VARSEG(a(0)) and VARPTR(a(0)) would be replaced with an integer variable equal to zero. Example: REM $INCLUDE: 'qlib.bi' REM I want to create a memory space to store 180 short integers bytes% = 180: shortseg% = AllocMem(bytes%) REM next I'll establish initial values for each short integer a% = 0 FOR i= 0 to 179 CALL WriteShort(shortseg%, a%, i%, value%) NEXT i ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: s% = ASCII(st$) object code: ascii.obj ASCII returns the ASCII value of the first letter of the string st$. This is similar to BASIC's ASC(st$) function, except that ASCII returns -1 if str$ is a nul string, instead of stopping the program with an "Illegal Function Call" error message or requiring BASIC's ON ERROR. Example: REM $INCLUDE: 'qlib.bi' s% = ASCII(st$) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: i% = Bit2INT(bitstring$) object code: bit2int.obj Bit2INT converts a bit pattern as represented in the string bitstring$ into an integer value. This may be used to develop bit patterns for graphics applications. If Bit2INT is used for this purpose, bitstring$ should be no longer than 8 characters. Bit2INT examines each character in bitstring$ and sets bits in bitvalue% corresponding to non-zero characters in bitstring$. Example: REM $INCLUDE: 'qlib.bi' bitstring1$ = "10101010" bitstring2$ = "01010101" bitvalue1% = Bit2INT(bitstring1$) bitvalue2% = Bit2INT(bitstring2$) pattern$ = CHR$(bitvalue1%) + CHR$(bitvalue2%) CALL FillPattern(pattern$) ' this results in a fill . ' pattern of alternating . ' light and dark pixels. . ' See FillPattern in ' GRAPHICS.DOC ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: CombineINTArray(s0%, p0%, s1%, p1%, n%, add%) object file: combine0.obj Subroutine: CombineLNGArray(s0%, p0%, s1%, p1%, n%, add%) object file: combine1.obj Subroutine: CombineSNGArray(s0%, p0%, s1%, p1%, n%, add%) object file: combine2.obj Subroutine: CombineDBLArray(s0%, p0%, s1%, p1%, n%, add%) object file: combine3.obj CombineArray subroutines add Array1() to Array0() or subtract Array1() from Array0(). Array0() is altered; Array1() remains unchanged. If add% = 1, Array1() is added to Array0(). If add% = -1, Array1() is subtracted from Array0(). N% is the number of array elements. CombineINTArray is for INTEGER arrays, CombineLNGArray is for LONG integer arrays, CombineSNGArray is for SINGLE arrays and CombineDBLArray is for DOUBLE arrays. Note that BOTH arrays must be the same type. CombineSNGArray and CombineDBLArray use the 8087 if available or BASIC's 8087 emulator if no math coprocessor is in the computer. To preserve compatability with future versions of CombineArray subroutines, use only add% = 1 or add% = -1. Example: DEFINT A-Z DIM Array0(99), Array1(99) . ' program establishes values of arrays . . s0% = VARSEG(Array0(0)): p0% = VARPTR(Array0(0)) S1% = VARSEG(Array1(0)): p1% = VARPTR(Array1(0)) n% = 100 ' all array elements, from 0 through 99 type% = 1 ' add array1 to array0 CALL CombineINTArray(s0%, p0%, s1%, p1%, n%, type%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: CopyMem(fromSEG%, fromOFF%, toSEG%, toOFF%, bytes%, crt%) object file: copymem.obj Copies data from one part of memory to another. You supply the source segment and offset, destination segment and offset, and number of bytes to move (0 - 32767). This can be used to duplicate numeric arrays, or to copy to or from the video buffer. CopyMem will wait for retrace periods before copying any data if crt% = -1 (to avoid "snow" when copying to or from CGA video memory). Use crt% = 0 if not copying to or from video memory. Example: DIM Array1%(1999) ' 4000-byte array CALL GetCRT(crt%) ' crt% = -1 if monitor = CGA fromSEG% = &HB800 ' CGA / EGA video memory segment fromOFF% = 0 ' start of video memory buffer bytes% = 4000 ' 25 rows x 160 bytes per row toSEG% = VARSEG(Array1%(0)) toOFF% = VARPTR(Array1%(0)) CALL CopyMem(fromSEG%, fromOFF%, toSEG%, toOFF%, bytes%, crt%) REM we just stored the entire screen in array Array1%() ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: Date2LNG(month%, day% year%, date&) Subroutine: LNG2Date(month%, day% year%, date&) object file: date2lng.obj Date2LNG compresses a date into a long integer for storage. LNG2Date restores the date from the compressed value. Example: month% = 7 day% = 20 year% = 2052 CALL Date2LNG(month%, day%, year%, date&) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: day$ = DayName(day%) object file: dname.obj (q$mname.obj, strncpy.obj) DayName returns an ASCII string with the day name, given a day% number from 1 to 7. Unlike an array of day names dimesioned by BASIC and stored as an array of variable-length strings, DayName's data is stored outside of DGROUP, freeing that precious space for other string data. Example: REM $INCLUDE: 'qlib.bi' day% = 1 ' Sunday PRINT DayName(day%) ' prints "Sunday" ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: day% = DayOfWeek(month%, date%, year%) object file: dayoweek.obj Returns the day of week (1=Sunday through 7=Saturday) given a valid date. Valid dates are from Jan 1, 1980 through Dec 31, 2099. Day% = 0 if the date passed to the subroutine is not valid. Example: REM $INCLUDE: 'qlib.bi' month% = 2 date% = 2 year% = 1990 ' ground hog's day, 1990 day% = DayOfWeek(month%, date%, year%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: n$ = DBL2STR(n#, dec%, opt%) object files: dbl2str.obj (q$sfmt.obj) Function: n$ = SNG2STR(n!, dec%, opt%) object files: sng2str.obj (q$sfmt.obj) DBL2STR and SNG2STR convert a DOUBLE or SINGLE number to an ASCII string usable by QPrint, GPrint and other QLIB subroutines, with formatting options. n# or n! is the number you want converted, dec% is the number of decimal places you want in the string and opt% is an option code. DBL2STR and SNG2STR options are: 1 = negative numbers enclosed by parentheses 2 = thousands separated by commas 4 = truncate decimals (default is round decimals) options may be combined with BASIC's OR operator. Example: REM $INCLUDE: 'qlib.bi' n! = -1234.567 dec% = 2 ' 2 decimal places opt% = 1 OR 2 ' parentheses and commas n$ = SNG2STR(n!, dec%, opt%) ' n$ = "(1,234.57)" ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: DelArray2(VARSEG(a%(0)), VARPTR(a%(0)), i%, n%) Subroutine: DelArray4(VARSEG(a!(0)), VARPTR(a!(0)), i%, n%) Subroutine: DelArray8(VARSEG(a#(0)), VARPTR(a#(0)), i%, n%) object file: delarray.obj DelArray subroutines delete array element a(i) from the array and close the resulting gap. n% is the maximum array subscript. DelArray2 is used with 2-byte data, such as INTEGERs. DelArray4 is for 4-byte data, such as SINGLE or LONG. DelArray8 is for 8-byte data, such as DOUBLE or BC7's CURRENCY data type. Example: DIM a%(99) ' array of 100 elements, a(0) -> a(99) . ' INTEGER data type . . REM I want to delete a%(14) and move a%(15) through a%(99) up i% = 14: n% = 99 CALL DelArray2(VARSEG(a(0)), VARPTR(a(0)), i%, n%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: DelVSTRArray(VARPTR(a$(0)), i%, n%) object file: delvstr.obj Deletes a$(i) from an array of variable-length strings, and moves a$(i+1) through a$(n) forward. a$(n) will be moved to a$(n-1), and the new a$(n) will be a nul string. Example: DIM a$(100) . . . i% = 10: n% = 100 CALL DelVSTRArray(VARPTR(a$(0)), i%, n%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: i% = Find1(s%, p%, n%, value%) object file: find1.obj Function: i% = Find2(s%, p%, n%, value%) object file: find2.obj Function: i% = Find4(s%, p%, n%, value&|value!) Function: i% = Find8(s%, p%, n%, value#|value@) object file: find4.obj Find1, Find2, Find4 and Find8 find the first occurance of a value in an array. Find1 is for QLIB's SHORT arrays, Find2 is for INTEGER arrays, Find4 is for LONG arrays or for SINGLE arrays, Find8 is for DOUBLE or BC7's CURRENCY arrays. Note that value's data type must match the array's data type. I% is returned -1 if value is not found or if n% = 0. Example: REM $INCLUDE: 'qlib.bi' ' QLIB.BI has all the function declarations DIM a#(99) ' 100 DOUBLE values n% = 100 ' gonna search the whole array . . . s% = VARSEG(a#(0)): p% = VARPTR(a#(0)) ' establish pointers to array, start at a#(0) value# = .123456789# i% = Find8(s%, p%, n%, value#) IF i% = -1 GOTO Drat ' value# isn't in the array ' else a#(i%) = value# ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: FreeMem(segmentaddr%) object file: allocmem.obj (q$alloc.obj) FreeMem releases memory blocks allocated by QLIB (such as by AllocMem, ScreenMem and WindowMem). If you do not release the memory block after you are done using it, that memory will not be available to your program for other uses. See ScreenSave, ScreenRestore and ScreenMem in VIDEO.DOC for an example of FreeMem's use. See also AllocMem in DATA.DOC. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: GetTime(hour%, min%, sec%) object file: gettime.obj GetTime returns the system time. Hour% is from 0 to 23, min% and sec% are 0 through 59. Example: CALL GetTime(hour%, min%, sec%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: InsArray2(s%, p%, i%, n%, value%) Subroutine: InsArray4(s%, p%, i%, n%, value!) Subroutine: InsArray8(s%, p%, i%, n%, value#) object file: insarray.obj InsArray subroutines insert value% (or !, @, #, &) in an array of n% elements at position i%, moving a(i) through a(n-1) to a(i+1) through a(n) to make space. The previous a(n) is lost. InsArray2 is for 2-byte INTEGER data, InsArray4 is for 4-byte SINGLE or LONG data, and InsArray8 is for 8-byte DOUBLE or BC7's CURRENCY data. Note that the data type of value must be the same as the data type of the array. Example: DIM a&(100) . . . value& = 1019876 ' want to put this in the array i% = 75 ' at a(75), moving a(75) through n% = 100 ' a(99) to make room. s% = VARSEG(a&(0)): p% = VARPTR(a&(0)) CALL InsArray4(VARSEG(s%, p%, i%, n%, value&) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: InsVSTRArray(VARPTR(a$(0)), i%, n%, newstring$) object file: insvstr.obj Similar to the InsArray subroutines, above, but works with an array of variable-length string data. n% is the total number of strings in the array, newstring$ is inserted in the array at a$(i), a$(i) through a$(n-1) are moded to a$(i+1) through a$(n), and the previous a$(n) is lost. Example: DIM a$(40) newstring$ = "the new string data" i% = 20: n% = 40 CALL InsVSTRArray(VARPTR(a$(0)), i%, n%, newstring$) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: c$ = InsertString(a$, b$, i%) object file: insstr.obj InsertString inserts b$ in a$ at position i% in a$. Example: REM $INCLUDE: 'qlib.bi' a$ = "a day in paradise" b$ = "nother" i% = 2 c$ = InsertString(a$, b$, i%) REM returns c$ = "another day in paradise" ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: i% = InString(search$, pattern$, start%) object files: instring.obj (q$strstr.obj) Function: i% = InStringR(search$, pattern$, start%) object files: instrr.obj (q$srev.obj, q$strstr.obj) Function: i% = InString2(search$, pattern$, start%) object files: instr2.obj (q$tstr.obj, q$strstr.obj) Function: i% = InString2R(search$, pattern$, start%) object files: instr2r.obj (q$tstr.obj, q$srev.obj, q$strstr.obj) Similar to BASIC's INSTR function, InString will find the first occurrence of pattern$ in search$, and will return position% = position in search$ where pattern$ matches. Start% is the position in search$ where InString begins looking for pattern$. InString2 is case-insensitive, meaning that upper case A-Z are treated the same as lower case a-z. InStringR (Reverse) searches from the end to the start of search$. Start% is the position in search$ where InStringR begins it's search. To search the entire search$, start% should be LEN(search$) or greater. InString2R is a case-insensitive reverse INSTR-like function. Example: REM $INCLUDE: 'qlib.bi' search$ = "This is a test string" pattern$ = "is" start% = 1 ' begin search at first char in Search$ position% = InString(search$, pattern$, start%) ' returns position% = 3 start% = 4 ' begin search at fourth char in Search$ position% = InString(search$, pattern$, start%) ' returns position% = 6 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: i% = InStringCount(search$, pattern$, start%) object files: instr3.obj (q$strstr.obj) InStringCount counts the number of times pattern$ is found in search$, beginning at start% in search$. Example: REM $INCLUDE: 'qlib.bi' search$ = "There is a moose with the mouse" pattern$ = " mo" start% = 1 ' search entire pattern$ count% = InStringCount(search$, pattern$, start%) REM in this case count% = 2 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: INT2SNG(a%, a!) object file: int2sng.obj Subroutine: LNG2SNG(a&, a!) object file: lng2sng.obj INT2SNG and LNG2SNG are similar to BASIC's a! = CSNG(a%) and a! = CSNG(a&) commands, except they are up to 30% faster than QuickBASIC. 8087 not required. Example: a% = 12345 CALL INT2SNG(a%, a!) ' a! now equals 12345 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: n$ = INT2STR(a%, options%) object file: int2str.obj Function: n$ = LNG2STR(a&, options%) object file: lng2str.obj INT2STR and LNG2STR are similar to BASIC's STR$(a%) function, with the addition of flexible number format options. Number$ may be used with QLIB's video output subroutines. Formatting options include negative numbers in accounting format (enclosed by parentheses) and commas after thousands. LNG2STR's number$ is 17 characters long, and INT2STR creates a string 10 characters long. In both cases, the number will be right- justified in number$. If a% (or a&) is non-negative and accounting format is selected, a space will be included to the right of the number to justify it with negative numbers in the same format. Example: REM $INCLUDE: 'qlib.bi' a% = 24561 options% = 2 ' include commas options% = options% OR 1 ' accounting format number$ = INT2STR(a%, options%) CALL Qprint(number$, etc... ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: LNG2Date(month%, day%, year%, date&) See Date2LNG ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: i% = MaxINTArray(aSEG%, aPTR%, n%) Function: i% = MinINTArray(aSEG%, aPTR%, n%) object files: (medium model) maxmin0.obj (huge model) maxmin0.obj, lowds2hi.obj Function: i% = MaxLNGArray(aSEG%, aPTR%, n%) Function: i% = MinLNGArray(aSEG%, aPTR%, n%) object files: (medium model) maxmin1.obj (huge model) maxmin1.obj, lowds2hi.obj Function: i% = MaxSNGArray(aSEG%, aPTR%, n%) object files: (medium model) maxsng.obj (huge model) maxsng.obj, lowds2hi.obj Function: i% = MaxDBLArray(aSEG%, aPTR%, n%) object files: (medium model) maxdbl.obj (huge model) maxdbl.obj, lowds2hi.obj Function: i% = MinSNGArray(aSEG%, aPTR%, n%) object files: (medium model) minsng.obj (huge model) minsng.obj, lowds2hi.obj Function: i% = MinDBLArray(aSEG%, aPTR%, n%) object files: (medium model) mindbl.obj (huge model) mindbl.obj, lowds2hi.obj INT, LNG, SNG and DBL functions find the array element with maximum or minimum value between begin% and begin + n%. 80x87 not required. These functions are very fast. Example: REM $INCLUDE: 'qlib.bi' DIM a%(99) ' 100 element integer array . . . begin% = 0 ' start with the first array element n% = 90 ' look at the first 90 array elements ' a%(0) -> a%(89) aSEG% = VARSEG(a%(begin%)) aPTR% = VARPTR(a%(begin%)) i% = MaxINTArray(aSEG%, aPTR%, n%) PRINT "the maximum value is"; a%(i% + begin%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: i% = MaxDBLb(seg%, ptr%, n%, bytes%) object files: (medium model) maxdbl.obj (huge model) maxdbl.obj, lowds2hi.obj Function: i% = MinDBLb(seg%, ptr%, n%, bytes%) object files: (medium model) mindbl.obj (huge model) mindbl.obj, lowds2hi.obj Function: i% = MaxINTb(seg%, ptr%, n%, bytes%) Function: i% = MinINTb(seg%, ptr%, n%, bytes%) object files: (medium model) maxmin0.obj (huge model) maxmin0.obj, lowds2hi.obj Function: i% = MaxLNGb(seg%, ptr%, n%, bytes%) Function: i% = MinLNGb(seg%, ptr%, n%, bytes%) object files: (medium model) maxmin1.obj (huge model) maxmin1.obj, lowds2hi.obj Function: i% = MaxSNGb(seg%, ptr%, n%, bytes%) object files: (medium model) maxsng.obj (huge model) maxsng.obj, lowds2hi.obj Function: i% = MinSNGb(seg%, ptr%, n%, bytes%) object files: (medium model) minsng.obj (huge model) minsng.obj, lowds2hi.obj Similar to MaxINTArray and MinINTArray, but the byte increment between array elements to search is specified. This is handy for multi-dimensional arrays. This is best explained with an example. (example on next page) (MaxINTb example) DEFINT A-Z DECLARE FUNCTION MaxINTb% (s, p, n, bytes%) ' dimension a 40- by 40 integer array DEFINT A-Z DIM a(39, 39) ' fill the array with random numbers FOR j = 0 TO 39 FOR i = 0 TO 39: a(i, j) = CINT(100 * RND): NEXT i NEXT j ' clear the screen to show the results ' I want to find the maximum value between a(20, 0) and a(20, 39) CLS FOR i = 0 TO 39: PRINT a(20, i): NEXT i ' search 40 data points n = 40 ' get segment and offset address for a(20, 0) s = VARSEG(a(20, 0)): p = VARPTR(a(20, 0)) ' calculate the byte space between successive array elements ' this works whether you're in row-major or column-major mode ' recall that p% = VARPTR(a(20, 0)) bytes% = VARPTR(a(20, 1)) - p% ' call the function; the array element with the highest value from ' a(20, 0) to a(20, 39) is a(20, (0+i)) i = MaxINTb(s, p, n, b) PRINT: PRINT a(20, i); ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: i% = MaxVSTRArray(o%, n%) (QB4.x only) Function: i% = MinVSTRArray(o%, n%) (QB4.x only) object file: maxmin5.obj Finds longest or shortest string in a variable-length string array. o% = VARPTR(a$(start%)), and n% is the number of array elements to search. Example: REM $INCLUDE: 'qlib.bi' DIM A$(99) ' an array of 100 variable-length strings . ' program establishes strings . . i% = MaxVSTRArray(VARPTR(a$(0)),100) PRINT "The longest string in the array is " + a$(i%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: month$ = MonthName(month%) Object file: mname.obj (q$mname.obj, strncpy.obj) MonthName returns an ASCII string with the month name, given a month% number from 1 to 12. Unlike an array of month names dimesioned by BASIC and stored as an array of variable-length strings, MonthName's data is stored outside of DGROUP, freeing that precious space for other string data. Example: REM $INCLUDE: 'qlib.bi' month% = 1 ' January PRINT MonthName(month%) ' prints "January" ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: MulINTArray(aSEG%, aPTR%, n%, number!) Subroutine: MulLNGArray(aSEG%, aPTR%, n%, number!) Subroutine: MulSNGArray(aSEG%, aPTR%, n%, number!) Subroutine: MulDBLArray(aSEG%, aPTR%, n%, number#) Subroutine: MulINTb(aSEG%, aPTR%, n%, number!, bytes%) Subroutine: MulLNGb(aSEG%, aPTR%, n%, number!, bytes%) Subroutine: MulSNGb(aSEG%, aPTR%, n%, number!, bytes%) Subroutine: MulDBLb(aSEG%, aPTR%, n%, number#, bytes#) object file: mularray.obj MulArray subroutines multiply n% elements of an array by a constant real number. MulArray subroutines use the 8087 if available, or use the 8087 emulator if no 8087 is in the computer. Note that DBL arrays are multiplied by a double-precision real number (number#), all other data types are multiplied by a single-precision real number (number!). With Mul???b subroutines, you must specify the byte increment between successive data elements. Example: DIM a#(99) ' 100-element array, double precision . . . number# = 4.78 n% = 50 ' multiply a#(0) through a#(49) by number# aSEG% = VARSEG(a#(0)) ' aSEG% = segment where a#(0) is stored aPTR% = VARPTR(a#(0)) ' aPTR% = offset of a#(0) in aSEG% CALL MulDBLArray(aSEG%, aPTR%, n%, number#) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: ReadSShort(ArraySeg%, ArrayPtr%, ShortOffset% Function: ReadUShort(ArraySeg%, ArrayPtr%, ShortOffset%) Subroutine: WriteShort(ArraySeg%, ArrayPtr%, ShortOffset%, value%) object file: shortint.obj Read/WriteShort subroutines provide support for short integers, allowing some integer arrays to be compressed to half the normal size. In order to use these subroutines, the data must be within the ranges shown: Signed short integers: -128 to 127 (use ReadSShort) unsigned short integers: 0 to 255 (use ReadUShort) A normal array must be dimensioned before these subroutines can be used. WriteShort stores value% in the array at byte offset ShortOffset%, and ReadShort subroutines return the number at ShortOffset% as value%. Be sure you know what you're doing if you use these subroutines. Example: REM $INCLUDE: 'qlib.bi' REM I want to store 300 integers in a Short integer array. REM The data I'm using falls within the range of values for REM short unsigned integers, 0 to 255. REM First, I need to dimension an array to hold the data. DIM array%(149) REM 150 integer array elements, 0 to 149, = 300 short integers, 0 to 299 REM The example below stores value% as ShortArray(200) value% = 125 n% = 200 ArraySeg% = VARSEG(array%(0)) ArrayPtr% = VARPTR(array%(0)) CALL WriteShort(ArraySeg%, ArrayPtr%, n%, value%) REM now I'll read the value back ArraySeg% = VARSEG(array%(0)) ArrayPrt% = VARPTR(array%(0)) value% = ReadUShort(ArraySeg%, ArrayPtr%, n%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: c$ = ReplaceString$(a$, b$, i%, n%) object file: replace.obj ReplaceString replaces n% characters of a$ with b$, placing b$ at i in a$. See the example if you're still confused. Example: a$ = "a blue tree" b$ = "purple" i% = InString(a$, "blue", 1) ' find start of "blue" in a$ n% = 4 ' length of "blue" PRINT ReplaceString(a$, b$, i%, n%) ' prints "a purple tree" ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: Scramble(str$) Subroutine: UnScramble(str$) object file: scramble.obj Scramble does what its name implies; it scrambles the bits in the string str$ to make it unreadable. This can be handy for hiding passwords. Since some characters in str$ may be translated to end-of-file or carriage return marks, a scrambled string saved to disk should be written into a fixed field file or random-access file, not a sequential file. UnScramble should be used to restore str$. Example: password$ = "Chocolate Ice Cream" CALL Scramble(password$) ' password$ is now unreadable . . . CALL UnScramble(password$) ' password is restored ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: SetArray1(segment%, ptr%, n%, value%) object file: set2.obj Subroutine: SetArray1b(segment%, ptr%, n%, value%, bytes%) object files: (medium model) set2b.obj (huge model) set2b.obj, lowes2hi.obj Subroutine: SetArray2(segment%, ptr%, n%, value%) object file: set2.obj Subroutine: SetArray2b(segment%, ptr%, n%, value%, bytes%) object files: (medium model) set2.obj (huge model) set2.obj, lowes2hi.obj Subroutine: SetArray4(segment%, ptr%, n%, value![or value&]) Subroutine: SetArray8(segment%, ptr%, n%, value#[or value@]) Subroutine: SetArray4b(segment%, ptr%, n%, value![or value&], bytes%) Subroutine: SetArray8b(segment%, ptr%, n%, value#[or value@], bytes%) object files: (medium model) set4.obj (huge model) set4.obj, lowes2hi.obj Set n% elements of an array to a value. Note that the value passed to the subroutine is the same data type as the array. SetArray1 is for QLIB's short integer arrays, SetArray2 is for INTEGER arrays, SetArray4 is for LONG or SINGLE arrays, and SetArray8 is for DOUBLE or BC7's CURRENCY arrays. With SetArray1b, SetArray2b, SetArray4b and SetArray8b, the increment between array elements (bytes%) must be specified. Example 1: DIM a%(99): n%=100 ' integer array of 100 elements . . value% = -6 s% = VARSEG(a%(0)) ' starting with first array element p% = VARPTR(a%(0)) CALL SetArray2(s%, p%, n%, value%) REM we just set each element of the array a%() to -6 Example 2: DIM a&(9999): n% = 1000 ' long integer array of 10000 elements . ' each array element is 4 bytes long . value& = 140 bytes% = 8 ' set only every other array element s% = VARSEG(a&(0)) p% = VARPTR(a&(0)) CALL SetArray4b(s%, p%, n%, value&, bytes%) REM we just set 1000 elements of the array a&() to 140 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: ShiftCUR(value@, factor%) (BC7/QBX only) Subroutine: SShiftCUR(value@, factor%) (BC7/QBX only) object file: shiftcur.obj Subroutine: ShiftINT(value%, factor%) Subroutine: SShiftINT(value%, factor%) object file: shift.obj Subroutine: ShiftLNG(value&, factor%) Subroutine: SShiftLNG(value&, factor%) object file: shiftlng.obj Shifts all the bits in an integer factor% times. If factor% is positive, the bits are shifted LEFT. This effectively multiplies the value by a power of two in most instances. If factor% is negative, the bits are shifted RIGHT ABS(factor%) times. This is similar in effect to an integer divide by a power of two. Shift and SShift subroutines differ in the way negative numbers are treated when shifting right. Shift will replace the bits shifted off the right end of the data with zeros at the left, thus making negative numbers do unpredictable things. SShift (Signed Shift) preserves the sign of the original value so that shifting the value right effectively divides the value by a factor% value of two. Note, however, that repeated SShifting of a positive value right results in value = 0, while a negative value SShifted right repeatedly ends up with value = -1. Example 1: VALUE% = 47: factor% = 3 CALL ShiftINT(VALUE%, factor%) REM we just shifted VALUE% left three bits REM (in this case getting 47 * 2^3, or 376) Example 2: VALUE% = 47: factor% = -3 CALL ShiftINT(VALUE%, factor%) REM we just shifted VALUE% right 3 bits REM (here getting 47 \ 2^3, or 5) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: ShiftINTArray(aSEG%, aPTR%, n%, factor%, oops%) Subroutine: SShiftINTArray(aSEG%, aPTR%, n%, factor%, oops%) object file: array1.obj Subroutine: ShiftLNGArray(aSEG%, aPTR%, n%, factor%, oops%) Subroutine: SShiftLNGArray(aSEG%, aPTR%, n%, factor%, oops%) object file: lngarray.obj Shifts the bits of any n% elements of an integer array ABS(factor%) times. Positive values of factor% shift array elements LEFT. This is equivalent to multiplying the element by a factor% power of 2 in most instances. Negative values of factor% cause an integer divide by an ABS(factor%) power of 2. OOPS% will be returned -1 if an overflow occurred. Oops% will also be -1 if any negative numbers are shifted left, thus the usefulness of oops% in these subroutines is limited. SShiftArray preserves the sign of right-shifted values. See SShiftINT for details. Example: DIM a%(100) n% = 20 factor% = 1 aSEG% = VARSEG(a%(0)) aOFF% = VARPTR(a%(0)) CALL ShiftINTArray(aSEG%, aOFF%, n%, factor%, oops%) IF oops% = -1 THEN PRINT "Oops, must have overflowed somewhere" REM assuming there were no negative numbers in the array ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: a% = SNG2INT(a!, oops%) object file: sng2int.obj Copies the integer portion of a single-precision number a! to the integer a%. This is similar to BASIC's a% = INT(a!) command, except SNG2INT is about 6 times faster without an 8087, and SNG2INT returns the error flag oops% = -1 if a! is too big, instead of crashing the program with an "overflow" error message. Does not require a math coprocessor. Range of usable numbers is -32768 to +32767. Example: REM $INCLUDE: 'qlib.bi' a! = 20956.64 a% = SNG2INT(a!, oops%) IF oops% THEN ' results usable? GOTO TooBig ' argh! try something else ENDIF ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: a& = SNG2LNG(a!, oops%) object file: sng2lng.obj Copies the integer portion of a single-precision number a! to the long integer a&. This is similar to BASIC's a& = INT(a!) command, except SNG2LNG is about 3 times faster without an 8087, and SNG2LNG returns the error flag oops% = -1 if a! is too big, instead of crashing the program with an "overflow" error message. Does not require a math coprocessor. Range of usable numbers is about -2147483500 to +2147483500. Example: REM $INCLUDE: 'qlib.bi' a! = 209587.64 a& = SNG2LNG(a!, oops%) IF oops% THEN ' results usable? GOTO TooBig ' argh! try something else ENDIF ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: SortINTArrayHI(aSEG%, aPTR%, n%) Subroutine: SortINTArrayLO(aSEG%, aPTR%, n%) object file: sortint.obj Subroutine: SortLNGArrayHI(aSEG%, aPTR%, n%) Subroutine: SortLNGArrayLO(aSEG%, aPTR%, n%) object file: sortlng.obj Subroutine: SortDBLArrayHI(aSEG%, aPTR%, n%) object file: sortsng0.obj Subroutine: SortDBLArrayLO(aSEG%, aPTR%, n%) object file: sortsng1.obj Subroutine: SortSNGArrayHI(aSEG%, aPTR%, n%) object file: sortdbl0.obj Subroutine: SortSNGArrayLO(aSEG%, aPTR%, n%) object file: sortdbl1.obj Sorts n% elements of an array. SortArrayHI subroutines arrange a() in descending order (highest first), SortArrayLO subroutines arrange a() in ascending order. 8087 not required. Example: DIM a%(999) ' integer array, 1000 elements . ' program establishes values . ' for a%() . n%=1000 ' sort all elements from low to high aSEG% = VARSEG(a%(0)) aPTR% = VARPTR(a%(0)) CALL SortINTArrayLO(aSEG%, aPTR%, n%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: SortVSTRArrayHI(o%, n%) Subroutine: SortVSTRArrayLO(o%, n%) object file: sortvstr.obj Subroutine: SortVSTRArrayHI2(o%, n%) Subroutine: SortVSTRArrayLO2(o%, n%) Object files: sortvst2.obj (maxmin5.obj) These subroutines sort a variable-length string array a$() from low to high or high to low. Note that for case-sensetive subroutines, "A" < "a" and "A" < "AA". SortVSTRArray2 subroutines are case-insensetive, so that "A" = "a" and "a" < "AA". o% is the address of the first element in the string array to be sorted, and n% is the number of strings to sort. Example: DIM a$(149) ' variable-length string array, 150 strings . ' program establishes strings . . start% = 10 n% = 140 ' sort through the remainder of the array ' be careful that n% + start% does not ' exceed the length of the array, or your ' program will crash o% = VARPTR(a$(start%)) ' start the sort with the 11th string CALL SortVSTRArrayLO(o%, n%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: position% = strchr(a$, a%) object file: strchr.asm Searches string a$ for the first occurance of character a%. This is similar to using INSTR(a$, CHR$(a%)) to search for a character, except that strchr is quicker than QuickBASIC. Example: REM $INCLUDE: 'qlib.bi' a$ = "A foggy day" a% = 32 ' look for first space position% = strchr(a$, a%) Function: a$ = StripChar(s$, t$) object file: strip1.obj Returns a string with all characters of t$ removed from s$. Example: REM $INCLUDE: 'qlib.bi' s$ = "$1,234,567.89" ' a formatted string representing a number t$ = "$," ' remove the non-numeric characters a$ = StripChar(s$, t$) PRINT a$ ' prints "1234567.89" ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: total# = SumINTArray(aSEG%, aPTR%, n%) object files: sumi2.obj (sumarray.obj) Function: total# = SumLNGArray(aSEG%, aPTR%, n%) object files: sumi4.obj (sumarray.obj) Function: total# = SumSNGArray(aSEG%, aPTR%, n%) object files: sumf4.obj (sumarray.obj) Function: total# = SumDBLArray(aSEG%, aPTR%, n%) object files: sumf8.obj (sumarray.obj) Adds n% array elements starting with a(start%) and returns the total as a real number. Note that the total is a double-precision real number for all SumArray routines. SumArray subroutines use the 80x87 if available, or use the 8087 emulator if no 80x87 is in the computer. Example: REM $INCLUDE: 'qlib.bi' DIM a#(99) ' 100-element array, double precision . . . start% = 10 n% = 50 ' total a#(10) through a#(59) aSEG% = VARSEG(a#(start%)) ' aSEG% = segment where a#(10) is stored aPTR% = VARPTR(a#(start%)) ' aPTR% = offset of a#(10) in aSEG% total# = SumDBLArray(aSEG%, aPTR%, n%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: Today(month%, day%, year%, weekday%) object file: today.obj Returns integer values for month (1 - 12), day of month (1 - 31), year (1980 - 2099), and day of week (1 - 7, Sunday through Saturday) from the system clock. Example: CALL Today(month%, day%, year%, weekday%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: l% = TrimRight(str$) object file: trimr.obj TrimRight returns the length l% of a string without its trailing blank spaces. This is similar to BASIC's RTRIM$ function. Example: REM $INCLUDE: 'qlib.bi' . . . length$ = TrimRight(st$) st$ = LEFT$(st$, length%) REM This example is equivalent to BASIC's st$ = RTRIM$(st$) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: UPcase(st$) Subroutine: LOcase(st$) object file: case.obj Converts each character in st$ to Upper case / Lower case. Example: st$ = "This is a string of characters" CALL UPcase(st$) REM now st$ = "THIS IS A STRING OF CHARACTERS"